Aminet 2

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / comm / mail / pmread.lzh / pmread.doc < prev next >

Wrap

Text File | 1992-10-18 | 27KB | 657 lines

PMREAD (Poor-Man's Reader) Version 0.99 by Paul T. Miller AREXX and UNIX scripts by Christopher B. Fury ©1992 by Paul Miller All Rights Reserved. NOTE: This is a pre-release Shareware evaluation copy of the PMRead system. This is NOT public domain. However, because this is Shareware you may share this with as many people, living or simulated, as you want, but you MAY NOT SELL IT! If you like this, and use it, you can send some money or cookies or buy me a beer or Jolt or something. You can also encourage your friends to do the same, assuming they like it too. This is how Shareware works! If want to contribute a Shareware donation, see section VI, AUTHOR INFO. However, this version of the PMRead system does not do everything that it is designed to do. This version allows automatic downloading and reading of news. It handles ageing and trimming of read articles. It will also let you open and read mail folders in the standard UNIX mail folder format. All configuration panels work, which allow you to generate aliases and mailing lists and generally set all sorts of options which aren't available. This is called "Crippleware" in that the package does work to a degree (if all you want to do is read news, you're fine, and the Shareware situation stands), but other features are available, for a fee. To obtain a fully-functional version of the PMRead system, read the final section VII, UPGRADING. ----------------------------------------------------------------------------- CONTENTS (Table of) ------------------- I. INTRODUCTION II. INSTALLATION 1. Installing PMRead 2. Configuring Term 3. Configuring PMRead III. USING PMREAD 1. Group Maintainance 2. Reading News 3. Posting News 4. Reading Mail 5. Posting Mail 6. Setting up a Mailing List 7. Aliases 8. Message Operations 9. The Killfile 10. Opening a Folder 11. Automatic Transactions IV. HOW PMREAD WORKS V. ABOUT PMREAD VI. AUTHOR INFO VII. UPGRADING ---------------------------------------------------------------------------- I. INTRODUCTION PMRead (Poor-Man's Reader) is part of a complete system for reading and posting Internet news and mail without SLIP or UUCP. It was designed, basically, because I don't have SLIP and I can't get a UUCP feed. I have news access but because our campus inbound modem pool is still an archaic 2400 baud, reading news is just too slow! PMRead is FAST FAST FAST! REQUIREMENTS: AmigaDOS 2.04 or greater 2 megabytes of RAM Lots of HD space (and for use with the UNIX Internet package) Term 2.3 or greater and modem A UNIX account with Internet news access PMRead uses an AREXX script called GetNews, which interfaces with Term 2.3 by Olan Barthel, to interact automatically with your UNIX account at a prescribed time to download news and mail and parse it into a form useable by the reader. This whole processed is detailed in HOW PMREAD WORKS, but the practical upshot of all this is that in the middle of the night all this stuff happens and in the morning you can read your news and mail, right on your Amiga. Neat, huh? II. INSTALLATION 1. Installing PMRead First, find a place on your hard drive to place the PMREAD utilities and data files. Make a directory somewhere - call it, oh, I don't know, maybe "PMRead" or something. Now, assign the logical device PMREAD: to this directory. This assignment should be placed in your s:user-startup file somewhere so PMREAD: is always assigned. Now, copy the contents of the archive into the PMREAD: directory. Ignore the unix archive for now. It's JUST that easy! Now, on to the hard stuff... 2. Configuring Term NOTE: If you're using PMRead with UUCP or just plan to read folders with it, you don't need to worry about any of this. Just go one to the next section. For automatic interaction with Term and your UNIX account, you'll need to do a little work. There should be an archive called unix.lzh in your directory. Decompress this in RAM or something and follow the directions in the README file. You'll need to upload a utility program called fn and compile it on your host system. You'll also need to upload a UNIX script called PMSend. Then you'll need to put the GetNews.rexx script in PMREAD:, along with PMLogin.rexx and PMLogoff.rexx, which you'll need to edit to log you in and out of your UNIX account. There are a couple of examples included, and some hints at the end of the instructions. I realize this seems like a lot of work, but if you're familiar with AREXX and you follow the instructions exactly you should have everything working in half an hour or less... 3. Configuring PMRead Now run PMRead. It's located in PMREAD:, so if you don't have PMREAD: added to your path (you don't need to), just go to the CLI and type run PMREAD:PMREAD [enter] or go to the PMREAD: directory and double-click on it's icon. You'll see the PMRead Groups window and the default groups provided to get you started. Don't worry about these now. Go to the Settings menu and select Term. The Term Preferences panel will open and allow you to set some options about what to do with Term (you do have Term, don't you?). If you won't be using the auto-download feature, you don't need to do anything here. TERM PREFERENCES ---------------- The "Term Path" field is where the GetNews arexx script looks for Term. The default is "TERM:". Note that it expects Term to be called "Term". The "Phone Entry" field is the name of the Term phonebook entry to dial. Currently, this item is not "really" supported. Since Term does not let us initiate a dial through a phonebook entry which automatically handles login/ logoff scripts, we have to do our login/logoff with the PMLogin and PMLogoff scripts. But for upward compatibility, inside Term, create a phonebook entry with a certain name, say, "MAILER", that dials your host computer. The "Phone Entry" field contains the name of this phonebook entry. It's used currently in the PMLogin script with a Term 'DIAL' command. The "Call Time" field is the time, in 24-hour format, that you want PMRead to initiate a news transfer. The format is hh:mm, where hh is a value from 0 to 23 and mm is a value from 0 to 59. If you don't want any automatic transfers, clear this field! HOST PREFERENCES ---------------- Type your full name into the "Full Name" field. Type your host user name in the "User Name" field. You should know what this means. If not, it's what you type at the "login:" prompt. Type your host name into the "Host Name" field. You should know what this means. If not, it's what's display when you login, and you get something like "Connected to <hostname>." My host name is "csugrad.cs.vt.edu". NOTE: The 'Full', 'User', and 'Host' names really aren't used for anything right now. Since mail and news is handled through your unix system, these should all be set up at that end. You can safely ignore these fields if you like. The "News Path" field is where incoming news is stored on your host system. I can't help you much here but it's probably something like "/usr/spool/news". In this directory you should see directories like "comp" and "alt". These are the roots for different news groups. For example, "comp" will contain "sys", "binaries", and "graphics", and so on. The "Mail Path" field is where incoming mail is stored on your host system. I can't help you much here but it's probably something like "/usr/spool/mail". Your user name should be a directory in the mail path. For example, on my system, my mail would be stored at "/usr/spool/mail/pmiller". PATH PREFERENCES ---------------- The "News Path" is where you want incoming News to be stored. I just have a directory in PMREAD: called Data, where Brent Spiner hangs out. No, really it's where News and the news database get stored. This is up to you, but I defaulted it to PMREAD:Data. The "Temp Path" is where news is downloaded from your host with Term. News is parsed and trimmed here too. This should probably in RAM somewhere, if you have enough to handle the volume of news you expect each night. I defaulted this to RAM:. IMPORTANT NOTE FROM YOUR SPONSOR: The "News Path" and "Temp Path" CAN NOT and MUST NOT be the same path. Okay? The "Folder Path" is where you commonly store your folders. This is strictly up to you, and is only used when you use the "Open Folder..." command from the "Folder" menu. This is just the default directory for looking for folders. You might want to make a subdirectory of PMREAD: called Folder if you like to keep them around. MISCELLANEOUS PREFERENCES ------------------------- Put the name of your text editor in the "Editor" field. This is called when you post news or mail. Put the name of your uuencode utility in the "UUencode" field. If uuencode is in your path, just "uuencode" will work, otherwise put the full path. Put the name of your uudecode utility in the "UUdecode" field. If uudecode is in your path, just "uudecode" will work, otherwise put the full path. The GetNews script lz's your news at the host before it downloads it. You'll need the public domain utility "LZ" to decompress the archive. LZ is included for your convenience. The "LZ Path" field should contain the full PATH ONLY to the LZ program. For some reason, sometimes AREXX doesn't see all of your path, so might not see LZ if it's in a utility directory somewhere. You can leave this field blank if AREXX can find LZ, but we suggest just putting the path there. I've left this blank because there's not really a suitable default I could offer. Maybe "dh0:utilities" ?? The "Max Articles" field is where you tell GetNews the maximum number of articles from each group to get. The first time you run PMRead, set this to some small number, like 5. If you want 'em all, put a "-1". "Get Groups" is the number of days to wait to download the master group list. This is a future enhancement for determining when new groups have been added to internet. This is not implemented yet, so you can ignore it. "Age" is the number of days to wait before deleting unread news. Read news gets deleted each night, but unread hangs around until it gets aged out. Don't make this number too big or you'll fill up your harddrive. Set this to "1" when you go away on a trip (or just turn your computer off!). Click on the font button to bring up a file-requester listing the fonts you can choose. The new font will be used next time you run the program or after you iconify and uniconify. There are various options down the right side. Here's what they do: ADD SIGNATURE - Attaches your signature (found in PMREAD:Signature) to the end of outgoing news and mail. KEEP KILLED - Doesn't actually throw away killed articles, but flags them as killed in the article window (a 'K' will appear before the article description). You must specifically select these to read them. FLAG REPLIES - This flags all public replies to a news article you posted. This lets you immediately see replies to your posts when the respondant decides to followup rather than reply directly. APPEND NEWS - This is a quick way of only showing new news. When this is set all news is deleted before the next batch is downloaded, regardless of whether or not you've read it all. IMMEDIATE REPLY IMMEDIATE POST IMMEDIATE MAIL - When any of these flags are set, the news/mail transaction wil occur immediately after you quit or iconify, rather than waiting until the specified transaction time (but only if you replied, posted, or mailed depending on the state of these flags: ie, if "Immediate Mail" is set and "Immediate Post" isn't, and you post, it'll still wait). SORT GROUPS - This option only sorts groups when going to the "Add Group" window. I put it in as an option because sorting that many groups is SLOW! You might want to run your PMREAD:AllGroups file through a text-file sorter instead. SHOW HEADERS - When this flag is set, the message header is displayed at the top of the message, otherwise it is omitted. QUOTE - When this flag is set, the message you are replying to or following up is quoted, and each line is preceded with a '>'. The "Snapshot" option from the Settings menu is used to save the positions and sizes of the Group, Article, and Message windows, if they're open. If you have more than one Message window open, the first one will be used. The next time the windows open, they will appear where you want them. Make sure to use the "Save Settings" option to save all of your preferences. These are stored as a text file in 'PMREAD:Config'. III. USING PMREAD 1. Group Maintainance The Groups window contains a list of all of the newsgroups you want to get news from. This window also contains your mailbox and any open folders or mailing lists you're subscribed to. Each group is labeled with the group address (your mailbox, folders, and mailist lists will use the appropriate name), followed by the total number of articles in the group and the total number of unread articles in parenthesis, like this '(total/unread)'. You can add and remove news groups interactively with the "Add" and "Remove" items from the "Group" menu. Select "Add" and the "Add Group" window will appear with a list of all the groups from the 'PMREAD:AllGroups' file. Double-click on a group or select one with the arrow keys and the enter key. The group will be added alphabetically in the list in the Groups window. Select "Remove" to remove the currently selected group. This item will only be available if that group's articles are not being displayed. 2. Reading News Select a group with the arrow keys, numeric keypad keys, or mouse. All lists in the program work this way. Double-click or press the return key to activate the Article window for that group. If there are no articles in the group this will accomplish nothing. If the Article window is already open the group's articles will be displayed in the Article window, otherwise the window will open first. The Article Window contains a list of the articles in the group. Each article is labeled with who the article (or message) is from, the message date (month.day), the number of lines in the article (or message), and the subject. The subject will be compressed to fit inside the window. If it is too long, only the beginning and end will be displayed, with ellipses (..) in the middle. This way you can always see the beginning and end of the subject. The total number of unread articles will be displayed in the titlebar in parenthesis, along with the name of group (or folder or mailing list). The Article status is specified at the beginning of the label. If the article has been read, there will be an 'R' at the beginning. If use have the KEEP KILLED flag set, there will be a 'K' if the message was killed. If this is an unread article, but from a previous day, it will be flagged with an 'O' (for OLD). If the article is a public followup to an article you posted, it will be flagged with a 'Y' (for YOU). If the message has an embedded uuencoded file, it will be flagged with a 'U'. Use the arrow keys or mouse to select an article. Double-click or press return to open the message window for that article. Multiple message windows can be open at once. Use the up/down arrow keys, numeric keypad, or scroller to view the message. You can also use the space bar to "more" to the next page. The titlebar will display the percentage of the message you've seen. When you get to the end, an inverted bar will display the subject of the next message, or the next group name if this is the last message in a group. To go to the next message, you can press the right arrow key, or, if you're already at the bottom of the message, press the space bar. Using the space bar, you can read all messages in all groups. To go back a message, press the left arrow. You can also use the backspace key to "more" back up the message, or, if you're at the top, go to the previous message. Press ESCAPE to close a message window or the article window. 3. Posting News To post news, position the highlight bar over the group you wish to post to in the Groups window, and select "Post" from the Group menu. PMRead will then invoke your editor, providing a 'Newsgroups:' and 'Subject:' field for you to modify at will. Remember to leave one blank space after the colon and the beginning of your header text. If the 'Add Signature' option is enabled your signature will be inserted for you at the end of the message. Fill out the subject field and add newsgroups to the newsgroups field if you want to crosspost. You can also add a 'Keywords:' or 'Reply-To:' field if you like in the header area. Type the body of your message after the header, and make sure to leave at least one blank line between the header and your text. This is VERY important! Save the message to put it in your out-basket for news. You can quit your editor without saving to abort the post. 4. Reading Mail If you have mail, a 'MAILBOX' group will appear at the top of the Groups list. Select and read mail messages exactly like you would read normal news, mailing list, or folder messages. 5. Posting Mail To post mail to someone, select "Mail" from the Mail menu. A window will pop up listing your aliases and a providing an edit-field where you can enter your destination manually. If you want to mail by alias, select the appropriate alias, make sure the 'To' field is empty (to make sure, activate it and press SHIFT+DELETE to clear it), and select 'OK'. Type in an address manually and select 'OK' to avoid using an alias. Hit ESCAPE or the window's close box to abort. Once you've selected the destination PMRead will invoke your editor, automatically filling in the 'To:' field and providing you a 'Subject:' field to enter the subject in. Remember to leave one space between the colon and your subject text. If you have the 'Add Signature' flag set your signature will automatically be added to the end of the message. Type in your message body after the header, with at least one blank line in between. When you're done, save the file to add it to your out-basket for mail. You can quit your editor without saving to abort the mail. 6. Setting up a Mailing List If you subscribe to mailing lists you'll know that you get mailing list messages in your mailbox. The Mailing List feature lets PMRead automatically redirect mailing list messages to their own "groups." Select "Mailing Lists" from the "Mail" menu to configure your mailing lists. The Mailing Lists window contains a list of all the active mailing lists, by name. Below this list are edit boxes which display the name and address. The name is provided by you and is what you see in the Groups window. The address is where the mailing list messages come from. Select "Add" to create a new, empty mailing list. Select "Remove" to remove the currently selected list. Change the "Name" and "Address" fields to rename the list or change the address. 7. Aliases Select "Aliases" from the "Mail" menu to edit your aliases. These are quick ways of specifying an address, or group of addresses, when you mail. This window contains two lists. The one on the left displays the aliases by name. The one on the right lists the address(es) where messages will go when you mail to the alias. To add a new alias, select the "Name" editbox and type in a name. When you press return the alias will be created. To add an address to the alias, type an address into the "Address" editbox under the address list. To remove a single address, select the "Remove" button under the address list. To remove an entire alias, select "Remove" from under the alias list. Aliases can also be edited by modifying the 'PMREAD:Aliases' text file. They are stored in a logical format which I'm sure you can figure out by looking at the example Aliases. 8. Message Operations REPLY To reply to a message, whether news or mail, you must have the message window open at that time. Select "Reply" from the Message menu. Your editor will be invoked with the necessary fields initialized and you can proceed as if you were posting. FOLLOWUP To followup to a news article, the message window for that article should be open. Select "Followup" from the Message menu. Your editor will be invoked with the necessary fields initialized and you can proceed as if you were posting. FORWARD To forward a mail or news message to another individual the message window must be open at the time. Select "Forward" from the Message menu. Your editor will be invoked with the necessary fields initialized and you can proceed as if you were posting. SAVE To save a message you are currently viewing select "Save" from the Message menu. A file requester will pop up. Select an existing folder or type in the name of one to create. The current message will be appended to the folder in mailbox format. NEXT/PREVIOUS The "Next" and "Previous" options under the Message menu work exactly like the left and right arrow keys, moving the current message to the next or previous in the group, folder, mailing list, or mailbox. 9. The Killfile With the killfile, you can kill messages by 'From' field, 'Subject', or globally. The global option is extremely useful if, for example, you're tired of hearing Marc Barrett's banter. Just select Global from the Killfile submenu (in the Message menu), type in 'Marc Barrett', and you can look forward to much more intelligent news. Beware, making global killfile keywords such as "the" and "a" will probably make your news-reading very boring. To kill a thread of messages by subject, just select Killfile->Subject when viewing the offending message. Future messages with that same subject will be killed. The same thing works with the 'From' field. If you don't want to hear from someone, but like hearing people's flames about that person, Select Killfile->From when viewing a message from the offending person. If you want to type a subject or name in directly, without having a message available, just edit the 'PMREAD:Killfile' file directly. The format is as follows: from: name goes here subject: subject goes here global: global keyword goes here 10. Opening a Folder Select "Open Folder" from the "Folder" menu to select a folder. This will bring up a file requester, which defaults to the folder path specified in the "Paths Configuration" panel. Select a folder (please make sure it's really a mailbox-format folder - I'd hate to think of what would happen if you selected a binary file instead... :) The folder will be added the group list in the Group window, popping up an Article window which displays the messages in the folder. At this point it's treated as any other group, except you can't go to other groups from a folder. 11. Automatic Transactions To get PMRead to automatically handle your news and mail transactions at the call time specified in the Term Configuration panel, you must keep PMRead running by iconifying it. Select "Iconify" from the "Groups" menu when you're doing using PMRead. PMRead will install an AppIcon on the Workbench which looks like a mailbox. Iconifying also sets the timer and instructs PMRead to execute the 'PMREAD:GetNews.rexx' script at the specified time. Remember that your PMLogin.rexx and PMLogoff.rexx scripts should also be PMREAD:. The flag on the AppIcon will go up if you have new mail. IV. HOW PMREAD WORKS The PMRead system is a bit complex. Basically, when you iconify, an Arexx port is created, along with the AppIcon and a timer to invoke the transaction automatically. When the timer goes off, the AREXX script 'GetNews.rexx' is executed. This script currently parses the 'PMREAD:Config' file to get the necessary information. First, TrimNews is run to age old and read news. It then executes 'PMLogin.rexx', which you supply, to log you into your UNIX account and get you to the command prompt. The AREXX script then uses a UNIX script called PMSend and a program called FN which you need to compile on your host. These scripts and programs grab new news and mail, archive it, and download the data to the temporary directory specified in your config file. ParseNews is run which generates the news database in the temporary directory. ParseNews also handles message killing, flagging responses to your posts, and uuencode-embedded data detection. The new news and database information are appended to the existing data. Mail is handled similarly. Next new news and mail are posted using standard unix mailers. Finally, 'PMLogoff' is called to log you off your system. 'GetNews.rexx' instructs PMRead via AREXX that everything is done, notifies it if there is new mail (so the flag can go up) and shuts down. Please see Chris's GetNews.doc file for more information on all the stuff that's happening here. NOTE: All news, mail, and folders is stored in the standard mailbox format. This is transparent to the user, but means that messages containing the word 'From ' as the first five charcters of any line are modified so that 'From ' does NOT appear as the first five characters (usually by prepending the line with a '>'). Mailbox messages ALWAYS begin with a 'From ' line. FN on the UNIX end parses news articles into the mailbox format for parsing on the Amiga end. Outgoing news and mail is parsed into this format for parsing on the UNIX end when messages are posted and mailed. Therefore, it is vitally important not to mess with news and mail files directly. V. ABOUT PMREAD PMRead was written in "C" and built with SAS/C 6.0 on an Amiga 3000 running Workbench 3.0. Because there is no specific control over ListView GadTools gadgets under V39, I had to write my own. These look exactly like the GadTools ones except they're keyboard controllable and the highlight bar behaves a bit differently. VI. AUTHOR INFO PMRead and FN were written by Paul T. Miller. He can be reached on internet at: pmiller@csugrad.cs.vt.edu By normal mail: P.O. Box 635 Blacksburg, VA 24063-0635 GetNews and PMSend were written by Christopher B. Fury. He can be reached on internet at: cfury@csugrad.cs.vt.edu If you need to reach Chris by regular mail just mail it to me and I'll pass it on. He lives on campus and moves around from year to year. VII. UPGRADING The full-featured version of PMRead supports: Mail News posting, followups, and replies, with quoting Killfile Aliases Mailing Lists Attaching of encoded files to outgoing messages Detaching of decoded files from incoming messages Folder creation and more... To upgrade, send $20 American to: Paul Miller P.O. Box 635 Blacksburg, VA 24063-0635 You have the option of getting a disk by snail mail or if you leave your email address I'll mail you a uuencoded copy of the system. POSSIBLE FUTURE ENHANCEMENTS Here are some ideas I'm kicking around: MIME (Multimedia Internet Mail) support UUCP support If, of course, you have any feedback, opinions, suggestions, or criticims, feel free to mail me or Chris. I hope you like it!